Summary

Two small follow-up fixes flagged in the session retro doc:

Fix 1: OpenAPI documents the cached aggregate endpoints. The Wave 4-L endpoints GET /api/v1/billing/usage and GET /api/v1/team/summary were already live and tested in production, but /openapi.json had no path entries for them. Agents reading the spec alone had no machine-readable signal that the cached aggregates existed, so they were forced to scan the full /resources list to compute the same numbers the dashboard already had pre-aggregated. This PR adds:

• Path entries with response examples + Cache-Control header documentation
• BillingUsageResponse, TeamSummaryResponse, TeamSummaryResourceCounts, UsageMetric schemas
• TestOpenAPI_CachedAggregateEndpointsDocumented guards both paths, schemas, and the Cache-Control header contract

Fix 2: agent_action surfaces on every middleware 401. middleware.RequireAuth was emitting the bare three-key 401 shape {ok:false, error:"unauthorized"} on auth rejection. Downstream handlers that go through respondError already emit the agent_action sentence for the "unauthorized" code (via codeToAgentAction in helpers.go), but middleware bypasses that helper to avoid a circular import. The fix inlines the same prose + login URL directly in a new respondUnauthorized helper so an agent inspecting any 401 from this API gets the same remediation guidance regardless of which layer rejected the request. Six new test cases in auth_agent_action_test.go cover every RequireAuth failure path (no header, malformed bearer, invalid JWT, wrong secret, expired JWT, bearer-only).

Test plan

• make test-unit — all packages green locally
• After merge: curl -sS https://api.instanode.dev/api/v1/resources | jq . returns agent_action + upgrade_url fields (was previously the bare three-key shape)
• After merge: curl -sS https://api.instanode.dev/openapi.json | jq '.paths | keys[] | select(test("billing/usage|team/summary"))' lists both new paths

Notes

• Fix 1's OpenAPI additions overlap with PR #(env-aware deployments branch) which also touched the same file with the same content. If that lands first, the openapi.go diff here will resolve to a no-op; the test + middleware changes are independent.
• agent_action matches the "unauthorized" entry in handlers.codeToAgentAction verbatim, so handler-emitted 401s and middleware-emitted 401s now return identical prose.

🤖 Generated with Claude Code